home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbnextrow.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  2.9 KB  |  100 lines
  1. .Na "dbnextrow" 
  2. .Aa
  3. .Fu
  4. Read the next result row.
  5. .Ih "row data, reading"
  6. .Ih "results row, reading"
  7. .Sy
  8. .Sf "STATUS dbnextrow(dbproc)"
  9. .Sp "DBPROCESS" "*dbproc"
  10. .Co
  11. .Bl
  12. .I "dbnextrow()"
  13. reads the next row of result data, starting with the first row returned from the \*S.
  14. Ordinarily, the next result row is read directly from the \*S.
  15. If the DBBUFFER option is turned on and rows have been read out of order by calling
  16. .I "dbgetrow()",
  17. the next row is read instead from a linked list of buffered rows.
  18. .Ih "DBBUFFER option"
  19. When \f2dbnextrow()\f1 is called,
  20. any binding of row data to program variables (as specified with \f2dbbind()\f1 or \f2dbaltbind()\f1) 
  21. takes effect.
  22. .Bl
  23. The application must successfully call
  24. .I "dbresults()"
  25. before it can make any calls to
  26. .I "dbnextrow()."
  27. .Bl
  28. To determine whether a particular command is one that returns rows and
  29. needs results processing with \f2dbnextrow()\f1, call \f2DBROWS()\f1 after \f2dbresults()\f1.
  30. .Bl
  31. Normally, each result row is processed in turn by repeatedly calling
  32. .I "dbnextrow()"
  33. until it returns NO_MORE_ROWS.
  34. To cancel the current set of results instead, call \f2dbcanquery\f1.
  35. After a call to \f2dbcanquery()\f1, it is safe to call \f2dbresults()\f1 again.
  36. .Bl
  37. The typical sequence of calls is:
  38. .ta +4n +4n +4n +4n +4n +4n
  39. .SD
  40. .so dbnextrow.ex
  41. .ED
  42. .Bl
  43. The \*S can return two types of rows:
  44. regular rows containing data from columns designated by a SELECT statement's \f2select-list\f1,
  45. and compute rows resulting from the COMPUTE clause.
  46. To facilitate the processing of result rows from \*S,
  47. \f2dbnextrow()\f1 returns different values according to the type of row.
  48. See the section ``RETURNS'' for details.
  49. .Bl
  50. To display \*S result data on the default output device,
  51. you can use \f2dbprrow()\f1 instead of \f2dbnextrow()\f1.
  52. .Bl
  53. An asynchronous version of \f2dbnextrow()\f1, called \f2dbnextrow_a()\f1, is available for VMS.
  54. .Bz
  55. .Pa
  56. .Pi dbproc
  57. A pointer to the DBPROCESS structure that provides the connection
  58. for a particular front end/\*S process.  It contains all the
  59. information that \*L uses to manage communications and data between the
  60. front end and \*S.
  61. .in -.375i
  62. .Re
  63. .br
  64. \f2dbnextrow()\f1 can return five different types of values:
  65. .Bl
  66. If a regular row is read,
  67. REG_ROW is returned.
  68. .Ih "regular row, determining"
  69. .Bl
  70. If a compute row is read,
  71. the \f2computeid\f1 of the row is returned.
  72. (See \f2dbaltbind()\f1 for information on the \f2computeid\f1.)
  73. .Ih "compute row, determining"
  74. .Ih "row type, determining"
  75. .Bl
  76. If there
  77. are no more rows to be read or the command didn't return any rows,
  78. NO_MORE_ROWS is returned.
  79. .Bl
  80. If buffering is turned on and reading the next row would cause the buffer
  81. to be exceeded,
  82. BUF_FULL is returned.
  83. In this case, no row will have been read. To read any more rows,
  84. at least one row must first be
  85. pruned from the top of the row buffer
  86. by calling
  87. .I "dbclrbuf()."
  88. .Bl
  89. If the routine was unsuccessful, FAIL is returned.
  90. .Bz
  91. .Sa
  92. dbaltbind,
  93. dbbind,
  94. dbcanquery,
  95. dbclrbuf,
  96. dbgetrow,
  97. dbnextrow_a,
  98. dbprrow,
  99. options
  100.